Crate surf

Source
Expand description

§Surf the web - HTTP client framework

Surf is a Rust HTTP client built for ease-of-use and multi-HTTP-backend flexibility. Whether it’s a quick script, or a cross-platform SDK, Surf will make it work.

  • Extensible through a powerful middleware system
  • Multiple HTTP back-ends that can be chosen
  • Reuses connections through a configurable Client interface
  • Fully streaming requests and responses
  • TLS enabled by default (native tls or rustls)
  • Built on async-std (with optional tokio support)

§Examples

let mut res = surf::get("https://httpbin.org/get").await?;
dbg!(res.body_string().await?);

It’s also possible to skip the intermediate Response, and access the response type directly.

dbg!(surf::get("https://httpbin.org/get").recv_string().await?);

Both sending and receiving JSON is real easy too.

#[derive(Deserialize, Serialize)]
struct Ip {
    ip: String
}

let uri = "https://httpbin.org/post";
let data = &Ip { ip: "129.0.0.1".into() };
let res = surf::post(uri).body_json(data)?.await?;
assert_eq!(res.status(), 200);

let uri = "https://api.ipify.org?format=json";
let Ip { ip } = surf::get(uri).recv_json().await?;
assert!(ip.len() > 10);

And even creating streaming proxies is no trouble at all.

let req = surf::get("https://img.fyi/q6YvNqP").await?;
let body = surf::http::Body::from_reader(req, None);
let res = surf::post("https://box.rs/upload").body(body).await?;

Setting configuration on a client is also straightforward.

use std::convert::TryInto;
use std::time::Duration;
use surf::{Client, Config};
use surf::Url;

let client: Client = Config::new()
    .set_base_url(Url::parse("http://example.org")?)
    .set_timeout(Some(Duration::from_secs(5)))
    .try_into()?;
    
let mut res = client.get("/").await?;
println!("{}", res.body_string().await?);

§Features

The following features are available. The default features are curl-client, middleware-logger, and encoding

  • curl-client (default): use curl (through isahc) as the HTTP backend.
  • h1-client: use async-h1 as the HTTP backend with native TLS for HTTPS.
  • h1-client-rustls: use async-h1 as the HTTP backend with rustls for HTTPS.
  • hyper-client: use hyper (hyper.rs) as the HTTP backend.
  • wasm-client: use window.fetch as the HTTP backend.
  • middleware-logger (default): enables logging requests and responses using a middleware.
  • encoding (default): enables support for body encodings other than utf-8.

Re-exports§

Modules§

Structs§

  • Body
    A streaming HTTP body.
  • Client
    An HTTP client, capable of sending Requests and running a middleware stack.
  • Config
    Configuration for surf::Clients and their underlying HTTP clients.
  • DecodeError
    An error occurred while decoding a response body to a string.
  • Error
    The error type for HTTP operations.
  • Request
    An HTTP request, returns a Response.
  • RequestBuilder
    Request Builder
  • Response
    An HTTP response, returned by Request.
  • Url
    A parsed URL record.

Enums§

Traits§

  • HttpClient
    An abstract HTTP client.
  • Status
    Provides the status method for Result and Option.

Functions§

  • client
    Construct a new Client, capable of sending Requests and running a middleware stack.
  • connect
    Perform a one-off CONNECT request.
  • delete
    Perform a one-off DELETE request.
  • get
    Perform a one-off GET request.
  • head
    Perform a one-off HEAD request.
  • options
    Perform a one-off OPTIONS request.
  • patch
    Perform a one-off PATCH request.
  • post
    Perform a one-off POST request.
  • put
    Perform a one-off PUT request.
  • trace
    Perform a one-off TRACE request.

Type Aliases§

  • Result
    A specialized Result type for Surf.